
"""应用场景
微服务架构：FastAPI 可以很好地作为微服务的一部分，利用其高效率和轻量化的特点。
API 后端开发：FastAPI 提供了一个强大而灵活的平台来创建 RESTful API，适用于各种类型的后端应用。
实时通信应用：FastAPI 支持 WebSocket，适合需要实时更新的应用，如聊天系统或在线游戏。
数据驱动的 Web 应用：FastAPI 可以与流行的数据库 ORM 集成，为数据密集型应用提供良好的支持。
机器学习/人工智能项目的部署：FastAPI 可以帮助将 ML 或 AI 模型部署为 RESTful API，使其可以被其他应用程序调用。
"""


# FastAPI的依赖注入非常强大，可以用于共享业务逻辑、权限验证、数据库会话等。
# 对于不需要在响应前完成的操作，可以使用后台任务（例如发送邮件、处理文件等）
# FastAPI内置了OAuth2密码流和JWT的支持，适用于用户认证。
"""
    使用 uname  password  --->  数据查询  ---->  如果正确创建token：create_access_token(data={"sub": user.username})
    ----->  token 的创建使用 jwt：jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
"""
# 使用APIRouter进行模块化：当应用变大时，使用APIRouter将路由分组到不同的模块中
# FastAPI使用Depends函数来声明依赖，支持函数、类和生成器三种形式
# 依赖注入的核心原理包括类型提示检查、依赖图构建和结果传递





"""
OpenAPI（以前称为 Swagger 规范）是一个用于定义 RESTful API 的标准格式。
它提供了一种描述 API 结构、端点、请求参数、响应数据等的通用语言，使得开发者可以更容易地理解和使用 API。
OpenAPI 规范支持 JSON 和 YAML 格式，并且是跨语言、跨平台的。


Swagger 是一个围绕 OpenAPI 规范构建的工具集。它包括了用于生成、可视化、测试和文档化 API 的各种工具。
例如，Swagger UI 是一个交互式的 Web 界面，它可以读取 OpenAPI 规范文件并生成易于使用的 API 文档
"""



"""依赖注入优点
降低耦合度：对象不需要知道如何创建它们的依赖项，这使得代码更易于测试、理解和维护。
更好的可扩展性：可以通过更改配置而不是修改代码来替换或添加依赖项。
更容易进行单元测试：可以在测试时轻松地替换依赖项为模拟对象，以便更好地隔离测试场景。
"""


""" FastAPI 如何  支持异步 I/O 的简要说明
基于 asyncio: FastAPI 建立在 asyncio 模块之上
使用 async def 定义你的路径操作函数，使其成为协程（coroutine）。
        这允许它们在事件循环中非阻塞地运行，并等待 I/O 操作完成，而不会阻止其他任务的执行   

依赖注入的异步支持: FastAPI 的依赖注入系统也支持异步依赖。这意味着你可以在需要时异步地初始化或获取依赖项。        
        
Starlette 库: FastAPI 实际上是构建在 Starlette 微框架之上的，而 Starlette 本身提供了对异步处理的支持
            FastAPI 可以利用 Starlette 的异步中间件、路由和其他功能

在高并发场景下：处理大量的数据库查询、文件读写或其他 I/O 密集型任，使用异步编程可以显著提高系统的性能
              不同的请求可以在同一时间被处理，不必按照顺序逐个完成






"""






# 实现文件上传
from fastapi import File, UploadFile
@app.post("/upload-file/")
async def upload_file(file: UploadFile):
    file_content = await file.read()
    with open("new_filename.txt", "wb") as new_file:
        new_file.write(file_content)

    await file.close()








# 在 FastAPI 中，处理会话（Session）和 Cookies 是通过 Starlette 库提供的功能实现的

from fastapi import Response

# 使用 Response 类的 .set_cookie() 方法来设置一个或多个 Cookies。
# 这个方法接受 cookie 名称、值和其他可选参数，如过期时间、路径等。
@app.get("/cookie/")
async def set_cookie(response: Response):
    response.set_cookie(key="my_cookie", value="the_value")



# FastAPI 会自动将请求头中的 “Cookie” 字段解析为字典，并将其作为 Request 对象的 .cookies 属性提供。
# 你可以在路径操作函数中访问此属性来读取请求中的 Cookies。
from fastapi import Request

@app.get("/read-cookie/")
async def read_cookie(request: Request):
    my_cookie = request.cookies.get("my_cookie")
    ...


#  FastAPI 中，没有内置的 Session 支持
# 通过集成第三方库，如 itsdangerous 或 secure-cookie-session 来实现会话管理。


# 虽然 FastAPI 没有直接支持基于 JWT（JSON Web Tokens）的会话管理，
# 但可以结合其他库，如 PyJWT 来实现 JWT 验证和授权。JWT 可以用于无状态的会话管理，
# 在每个请求中携带令牌并在服务器端验证它




# 通过 RedirectResponse 类实现 HTTP 重定向
from fastapi import RedirectResponse

@app.get("/redirect-me/")
async def redirect_me():
    url = "https://example.com/new-location"
    return RedirectResponse(url)
    # 以下是可选：

    # 默认情况下，RedirectResponse 使用 HTTP 状态码 307 (Temporary Redirect)。
    # 如果你想使用其他状态码（如 301, 302），
    # 可以通过在创建 RedirectResponse 时提供额外的 status_code 参数来指定
    # return RedirectResponse(url, status_code=status.HTTP_301_MOVED_PERMANENTLY)

    # 添加额外头部信息
    # headers = {"X-Custom-Header": "Some value"}
    # return RedirectResponse(url, headers=headers)






# 异常：

# 创建自定义异常类：捕获特定类型的错误
class MyCustomError(Exception):
    pass



# 抛出异常
@app.get("/my-endpoint/")
async def my_endpoint():
    if some_condition:
        raise MyCustomError("This is a custom error")  #  或者 ：  ValueError
    ...




# 全局异常处理：@app.exception_handler() 装饰器来定义全局异常处理器
@app.exception_handler(MyCustomError)
async def handle_my_custom_error(request: Request, exc: MyCustomError):
    return JSONResponse(
        status_code=status.HTTP_400_BAD_REQUEST,
        content={"error": str(exc)},
    )




# 路由级别的异常处理：
# 使用 FastAPI.include_router() 函数的 exception_handlers 参数 
# 这个参数应该是一个字典，其中键是异常类，值是处理这些异常的函数。
from fastapi import APIRouter,FastAPI
router = APIRouter()

@router.get("/my-route/")
async def my_route():
    ...

@router.exception_handler(MyCustomError)
async def handle_my_custom_error_for_this_route(request: Request, exc: MyCustomError):
    ...

app = FastAPI()
app.include_router(router, exception_handlers={MyCustomError: handle_my_custom_error_for_this_route})


# 标准 HTTP 异常:  预定义的异常类，如 HTTPException
from fastapi import HTTPException

@app.get("/standard-error/")
async def standard_error():
    raise HTTPException(status_code=404, detail="Not found")


# 除此外还可以使用 python 提供的 异常类






# https://github.com/s3rius/FastAPI-template     fastapi模板，自定义三方组件如reids，等，可以学习构建模板的原理，
# https://gitee.com/ktianc/kinit